home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / README.gtkdoc < prev    next >
Encoding:
Text File  |  2000-06-13  |  4.1 KB  |  109 lines
  1. Developers documentation using gtk-doc
  2. --------------------------------------
  3.  
  4. The goal is to provide useful source documentation. Right 
  5. now this is limited to libgimp since that is the part that 
  6. is used by third-party coders (plug-in developers). Other 
  7. parts of the code may follow later, but not before libgimp 
  8. is properly documented.
  9.  
  10. Principle
  11. ---------
  12. The documentation is extracted out of the source using 
  13. gtk-doc. We use a combination of comment blocks embedded 
  14. into the source and additional information added manually 
  15. into the SGML files. It is planned to extract useful 
  16. inforamtion about the PDB wrappers out of the PDB 
  17. (probably using pdbgen).
  18.  
  19.  
  20. Requirements
  21. ------------
  22. GIMP releases will contain a complete set of HTML files and
  23. the SGML files to create other formats. You will only need
  24. gtk-doc if you want to work on the documentation itself. 
  25. In that case you will need the following utilities:
  26.  
  27. Perl v5 - the main scripts are in Perl.
  28.  
  29. DocBook DTD v3.0 - This is the DocBook SGML DTD.
  30.     http://www.ora.com/davenport
  31.  
  32. Jade v1.1 - This is a DSSSL processor for converting SGML 
  33.     to various formats. 
  34.     http://www.jclark.com/jade
  35.  
  36. Modular DocBook Stylesheets (v1.19+ should be OK)
  37.     This is the DSSSL code to convert DocBook to HTML (and 
  38.     a few other formats). It's used together with jade.
  39.     http://nwalsh.com/docbook/dsssl
  40.  
  41. gtk-doc - This package automatically generates DocBook 
  42.     documentation for GTK+ and converts the DocBook 
  43.     documentation into HTML (and man pages in future).
  44.     http://www.gtk.org/rdp/download.html
  45.  
  46.  
  47. HOWTO
  48. -----
  49. Carefully read the README that comes with gtk-doc. Then 
  50. read it again! The following lines will only give you hints
  51. about how our system works. You should have understood the
  52. principles of gtk-doc before you touch it.
  53.  
  54. The system is already set up so unless there are substantial
  55. changes to the source e.g. new files were added, functions 
  56. were added, renamed or removed or parameters changed, there
  57. is no need to repeat the scan step or rebuild the templates.
  58.  
  59. The Makefile will only work if gtk-doc was successfully
  60. found when configure was ran. To rerun the scan step you also
  61. need to have gimp installed (the version you are documenting)
  62. and the correct version of gimptool should be found in your 
  63. PATH. If everything was set up correctly running a simple 
  64. make should do the trick and generate the SGML and HTML files 
  65. for you.
  66.  
  67.  
  68. In most cases you will work on the documentation by adding or
  69. editing comment blocks in the C source and by editing the 
  70. template SGML files in the tmpl dir. The following steps 
  71. should rebuild the documentation after a change:
  72.  
  73. make sgml  - Creates the SGML files from the templates found
  74.              in the tmpl dir and from the comment blocks found
  75.              in the source.
  76.  
  77. make html  - Build HTML pages out of the SGML files.
  78.  
  79.  
  80. If the source was changed (real changes as described above), 
  81. you will need to perform the following two steps before you can
  82. rebuild the sgml and html files:
  83.  
  84. make scan  -     Scans the header files and builds and runs a 
  85.                  binary that asks the GtkObjects to describe 
  86.          themselves. That way the hierarchy of widgets, 
  87.          arguments and signals are determined. If you
  88.          have added new objects, you will have to update
  89.          the MODULE.types files accordingly before you 
  90.          perform this step.
  91.  
  92. make templates - Merges the changes into the templates. This will 
  93.                  output warnings about any declarations which have 
  94.          been added/removed. Update the MODULE-sections.txt 
  95.          to include the new functions etc. in the 
  96.          appropriate sections, and delete ones which are 
  97.          no longer available. Run "make templates" again 
  98.          until there are no warnings output.
  99.              
  100.  
  101. More information
  102. ----------------
  103. Using the system as described above, you can write documentation without 
  104. any knowledge of SGML and DocBook, but when editing the templates you 
  105. will sometimes want to do a little extra structuring or markup. The best 
  106. source for information about DocBook seems to be "DocBook: The Definitive 
  107. Guide" which is available online at http://www.docbook.org/tdg/html/.
  108.  
  109.